<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: PRA          (Protected Register Access)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__group__pra.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">API Reference</a>  </div>
  <div class="headertitle">
<div class="title">PRA (Protected Register Access)</div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">General Description</h2>
<dl class="section note"><dt>Note</dt><dd>The Protection Register Access (PRA) driver is intended for the PSoC 64 devices only and provides other PDL drivers access to the registers that have secure access restrictions. It is not intended to be used directly by user application.</dd></dl>
<p>The PRA driver is used to protect the system from invalid configurations that could potentially cause the system to be unstable or indirectly allow access to registers and memory that are protected. This is done using several methods:</p><ul>
<li>Allow only valid register settings.</li>
<li>Force a specified sequence of operations when writing to a register.</li>
<li>Totally block access to registers that are deemed critical to security.</li>
<li>Allow only known, well defined system configurations.</li>
<li><p class="startli">Allow access to non-critical registers that are protected by a fixed PPU.</p>
<p class="startli">On PSoC 64 devices, secure firmware protects entire regions of registers with the fixed PPUs, however there are some registers within that regions that should not be protected but, are protected due to fixed PPU granularity.</p>
<p class="startli">The list of the registers that can be accessed by PRA driver directly is defined in the cy_pra.h file with the CY_PRA_INDX_ prefix.</p>
</li>
</ul>
<p>Most PDL drivers are not affected or use the PRA driver. Only the following PDL drivers are affected by this driver:</p><ul>
<li><a class="el" href="group__group__lvd.html">LVD (Low-Voltage-Detect)</a></li>
<li><a class="el" href="group__group__syslib.html">SysLib (System Library)</a></li>
<li><a class="el" href="group__group__sysclk.html">SysClk (System Clock)</a></li>
<li><a class="el" href="group__group__syspm.html">SysPm (System Power Management)</a></li>
<li><a class="el" href="group__group__arm__system__timer.html">SysTick (Arm&reg; System Timer)</a></li>
<li><a class="el" href="group__group__wdt.html">WDT (Watchdog Timer)</a></li>
<li><a class="el" href="group__group__flash.html">Flash (Flash System Routine)</a></li>
<li><a class="el" href="group__group__sysint.html">SysInt (System Interrupt)</a> (PSoC 64 CYB06xx7 devices only)</li>
<li><a class="el" href="group__group__prot.html">Prot (Protection Unit)</a> (PSoC 64 CYB06xx7 devices only)</li>
<li><a class="el" href="group__group__gpio.html">GPIO (General Purpose Input Output)</a></li>
</ul>
<p>The execution time of the functions that access the protected registers is increased on the PSoC 64 devices because the access is performed on Cortex-M0+ via the IPC command (both CPU cores run at 8 MHz):</p><ul>
<li>The access to the protected register may take about 50 us, while access to the unprotected one may take about 3 us.</li>
<li>The initial device configuration may take up to 1.75 ms for PSoC 64 devices, while for the other devices it may take about 0.3 ms.</li>
<li>The transition Active to DeepSleep to Active may take about 2 times longer.</li>
</ul>
<h1><a class="anchor" id="group_pra_basic_operation"></a>
Basic Operation</h1>
<p>The PRA driver uses an IPC channel to transfer register data between the user application running on the Cortex-CM4 and the secure Cortex-CM0+ CPU. The secure processor performs the data validation and correct register write sequence to ensure proper stable operation of the system. Function status and requested data is also returned via the IPC channel.</p>
<p>The PDL driver that accesses protected registers, generates request to the PRA driver and it passes request over the IPC to secure Cortex-M0+, where request is validated and executed, and, then, reports result back to the driver on Cortex-M4 side.</p>
<div class="image">
<img src="pra_high_level_diagram.png" alt="pra_high_level_diagram.png"/>
</div>
<h1><a class="anchor" id="group_pra_device_config"></a>
Device Configuration</h1>
<p>For PSoC 64 device, device configuration (like system clock settings and power modes) is applied on the secure Cortex-M0+. The device configuration can be initiated from either of the core or both the cores. The device configuration structure <a class="el" href="structcy__stc__pra__system__config__t.html">cy_stc_pra_system_config_t</a> is initialized with Device Configurator. For Cortext-M4 application, it passed to the secure Cortex-M0+ core through IPC for validation and register the update in the cybsp_init() function. For Cortext-M0+ application, this device configuration structure is directly validated and applied.</p>
<dl class="section note"><dt>Note</dt><dd>The external clocks (ECO, WCO, and EXTCLK) require additional configuration to be allowed to source CLK_HF0 (clocks both Cortex-M0+ and Cortex-M4 CPUs) in order to prevent clock tampering. See <a class="el" href="group__group__pra.html#group_pra_external_clocks">External Clock Sources</a> for details.</dd>
<dd>
The ALTHF (BLE ECO) is not allowed to source CLK_HF0 (clocks both Cortex-M0+ and Cortex-M4 CPUs) in order to prevent clock tampering.</dd>
<dd>
The internal low-frequency clocks (ILO and PILO) are not allowed to source the CLK_HF0 directly and through PLL or FLL.</dd>
<dd>
The clock source for Cortex-M4 SysTick cannot be configured with the Device Configurator. Enabling CLK_ALT_SYS_TICK will result in a compilation error. SysTick still can be configured in run-time with some limitations. For more details, refer to <a class="el" href="group__group__systick__functions.html#gaa8a72d8a278e4a3a970b4c4a021f3647">Cy_SysTick_SetClockSource()</a> in <a class="el" href="group__group__arm__system__timer.html">SysTick (Arm&reg; System Timer)</a>.</dd>
<dd>
When EXT_CLK is source to HF0 then the drive mode for EXT_CLK pin is hard coded to CY_GPIO_DM_HIGHZ. So user has to make sure this pin configuration is not overwritten from secure application.</dd></dl>
<h1><a class="anchor" id="group_pra_external_clocks"></a>
External Clock Sources</h1>
<p>The PSoC 64 devices must be provisioned with the external clocks (ECO, WCO, and EXTCLK) configuration before routing these clocks to CLK_HF0. To do that, update the JSON file (delivered with CySecureTools) with the "extclk" node in the custom data section as shown below. The configuration fields in the JSON file match the fields in the Device Configurator.</p>
<p>For more details, refer to the PSoC 64 Secure MCU Secure Boot SDK User Guide.</p>
<div class="fragment"><div class="line">For EXTCLK:</div><div class="line">    &quot;custom_data_sections&quot;: [&quot;extclk&quot;],</div><div class="line">    &quot;extclk&quot;: {</div><div class="line">            &quot;extClkEnable&quot;: 1,</div><div class="line">            &quot;extClkFreqHz&quot;: 24000000,</div><div class="line">            &quot;extClkPort&quot;: 0,</div><div class="line">            &quot;extClkPinNum&quot;: 0,</div><div class="line">            &quot;extClkHsiom&quot;: 0</div><div class="line">    }</div><div class="line"></div><div class="line">For ECO:</div><div class="line">    &quot;custom_data_sections&quot;: [&quot;extclk&quot;],</div><div class="line">    &quot;extclk&quot;: {</div><div class="line">            &quot;ecoEnable&quot;: 1,</div><div class="line">            &quot;ecoFreqHz&quot;: 24000000,</div><div class="line">            &quot;ecoLoad&quot;: 18,</div><div class="line">            &quot;ecoEsr&quot;: 50,</div><div class="line">            &quot;ecoDriveLevel&quot;: 100,</div><div class="line">            &quot;ecoInPort&quot;: 12,</div><div class="line">            &quot;ecoOutPort&quot;: 12,</div><div class="line">            &quot;ecoInPinNum&quot;: 6,</div><div class="line">            &quot;ecoOutPinNum&quot;: 7,</div><div class="line">    }</div><div class="line"></div><div class="line">For WCO:</div><div class="line">    &quot;custom_data_sections&quot;: [&quot;extclk&quot;],</div><div class="line">    &quot;extclk&quot;: {</div><div class="line">            &quot;wcoEnable&quot;: 1,</div><div class="line">            &quot;bypassEnable&quot;: 0</div><div class="line">            &quot;wcoInPort&quot;: 0,</div><div class="line">            &quot;wcoOutPort&quot;: 0,</div><div class="line">            &quot;wcoInPinNum&quot;: 0,</div><div class="line">            &quot;wcoOutPinNum&quot;: 1</div><div class="line">    }</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>The same "extclk" section is used for all external clocks. If more than one external clock source is required, please append its parameters.</dd></dl>
<h1><a class="anchor" id="group_pra_sram_power_config"></a>
SRAM Power Mode Configurations</h1>
<p>The PSoC 64 devices must be provisioned with the SRAM power mode configuration to protects secure core memory. To do that, update the JSON file (delivered with CySecureTools) with the "srampwrmode" node in the custom data section as shown below.</p>
<p>For more details, refer to the PSoC 64 Secure MCU Secure Boot SDK User Guide.</p>
<div class="fragment"><div class="line">&quot;custom_data_sections&quot;: [&quot;srampwrmode&quot;],</div><div class="line">&quot;sram0&quot;: [</div><div class="line">    {</div><div class="line">        &quot;macroNum&quot;: 1,      // bits 0</div><div class="line">        &quot;powerMode&quot;: 6,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF</div><div class="line">    },</div><div class="line">    {</div><div class="line">        &quot;macroNum&quot;: 2,      // bits 1</div><div class="line">        &quot;powerMode&quot;: 1,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF</div><div class="line">    },</div><div class="line">    {</div><div class="line">        &quot;macroNum&quot;: 65532,  // bits [15-2] = 0xFFFC</div><div class="line">        &quot;powerMode&quot;: 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF</div><div class="line">    }</div><div class="line">],</div><div class="line">&quot;sram1&quot;: [</div><div class="line">    {</div><div class="line">        &quot;macroNum&quot;: 1,      // bit 0</div><div class="line">        &quot;powerMode&quot;: 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF</div><div class="line">    }</div><div class="line">],</div><div class="line">&quot;sram2&quot;: [</div><div class="line">    {</div><div class="line">        &quot;macroNum&quot;: 1,      // bit 0</div><div class="line">        &quot;powerMode&quot;: 7,     // bit 2 = ON, bit 1 = RETAIN, bit 0 = OFF</div><div class="line">    }</div><div class="line">]</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>If a particular configuration(either SRAM or macro section) is not present in the policy file but available in the device then SRAM MACRO can be allowed to be modified to any of power modes (ON, RETAIN and OFF).</dd></dl>
<h1><a class="anchor" id="group_pra_standalone"></a>
Using without BSPs</h1>
<p>If PDL is used in Standalone mode without Board Support Package (BSP), do the following:</p><ul>
<li>1) Call the <a class="el" href="group__group__pra__functions.html#ga93393c7e6e2ca124ac0b331dcee6e78b">Cy_PRA_Init</a> function prior to executing API of any of the drivers listed above. By default, this function is called from <a class="el" href="group__group__startup__config__system__functions.html#ga93f514700ccf00d08dbdcff7f1224eb2">SystemInit</a> on both CPU cores.</li>
<li>2) Call the <a class="el" href="group__group__pra__functions.html#ga9eb129562cf959674d91dc11d37c374a">Cy_PRA_SystemConfig</a> function with the initial device configuration passed as a parameter. Refer to Section "Function Usage" of the <a class="el" href="group__group__pra__functions.html#ga9eb129562cf959674d91dc11d37c374a">Cy_PRA_SystemConfig</a> function for more details.</li>
</ul>
<h1><a class="anchor" id="group_pra_more_information"></a>
More Information</h1>
<p>See the device technical reference manual (TRM) reference manual (TRM) for the list of the protected registers.</p>
<h1><a class="anchor" id="group_pra_changelog"></a>
Changelog</h1>
<table class="doxtable">
<tr>
<th>Version</th><th>Changes</th><th>Reason for Change </th></tr>
<tr>
<td>2.40.1 </td><td>Coverity errors fixed. </td><td>Bug fixes.  </td></tr>
<tr>
<td>2.40 </td><td>Initialize internal data structure to initial values when external clock policy pointer is NULL to avoid null pointer de-referencing. </td><td>Defect fix.  </td></tr>
<tr>
<td rowspan="4">2.30 </td><td>System Configuration can be done from CM0+ using PRA API with CY_PRA_MSG_TYPE_SYS_CFG_FUNC and CY_PRA_FUNC_INIT_CYCFG_DEVICE arguments. </td><td>Enhancement based on customer feedback.  </td></tr>
<tr>
<td>System configuration structure is updated with appropriate value, when cm0+ application calls any PDL API accessing to FUNCTION_POLICY registers. </td><td>Enhancement based on customer feedback.  </td></tr>
<tr>
<td>Fixed MISRA 2012 violations. </td><td>MISRA 2012 compliance.  </td></tr>
<tr>
<td>Updated doxygen for External clock source to HF0. </td><td>Documentation enhancement.  </td></tr>
<tr>
<td>2.20 </td><td>Allowing external clocks (EXT_CLK, ECO and WCO) can be source to secure core. Provide interface for validating and configuring SRAM power modes. </td><td>External clock support and SRAM power mode configuration support.  </td></tr>
<tr>
<td rowspan="3">2.10 </td><td>Removed include of cy_gpio.h from the driver's c source files. Added some source code comments. </td><td>Source code cleanup.  </td></tr>
<tr>
<td>Updated attribute usage for the linker section placement. </td><td>Enhancement based on usability feedback.  </td></tr>
<tr>
<td>Fixed MISRA 2012 violations. </td><td>MISRA 2012 compliance.  </td></tr>
<tr>
<td rowspan="6">2.0 </td><td>Added PSoC 64 CYB06xx7 devices support. </td><td>New devices support.  </td></tr>
<tr>
<td>Updated <a class="el" href="group__group__pra__functions.html#ga93393c7e6e2ca124ac0b331dcee6e78b" title="Initializes the PRA driver: ">Cy_PRA_Init()</a> to compare the major and minor version of the PRA driver on the Cortex-M0+ and Cortex-M4 sides and halt Cortex-M4 if the versions are different.  </td><td>Ensure that the same PRA driver version is used on the Cortex-M0+ and Cortex-M4 sides.  </td></tr>
<tr>
<td>Fixed the location of the <a class="el" href="structcy__stc__pra__system__config__t.html">cy_stc_pra_system_config_t</a> description in the documentation.  </td><td>Documentation update.  </td></tr>
<tr>
<td>Corrected the reference to the <a class="el" href="group__group__arm__system__timer.html">SysTick (Arm&reg; System Timer)</a> function with the limitation description - <a class="el" href="group__group__systick__functions.html#gaa8a72d8a278e4a3a970b4c4a021f3647">Cy_SysTick_SetClockSource()</a>.  </td><td>Documentation update.  </td></tr>
<tr>
<td>The state of the following clocks changes only when the requested state differs from the actual state in the hardware: HF1-HF5, TIMER, PUMP, BLE_ECO, ILO, PILO, and WCO.  </td><td>Improved the <a class="el" href="group__group__pra__functions.html#ga9eb129562cf959674d91dc11d37c374a">Cy_PRA_SystemConfig()</a> function execution time.  </td></tr>
<tr>
<td>Renamed altHfFreq to altHFclkFreq in <a class="el" href="structcy__stc__pra__system__config__t.html">cy_stc_pra_system_config_t</a>. </td><td>Eliminated the naming conflict with the SysClk driver.  </td></tr>
<tr>
<td>1.0 </td><td>Initial version </td><td></td></tr>
</table>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
API Reference</h2></td></tr>
<tr class="memitem:group__group__pra__macros"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__pra__macros.html">Macros</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__pra__functions"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__pra__functions.html">Functions</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__pra__enums"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__pra__enums.html">Enumerated Types</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__pra__stc"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__pra__stc.html">Data Structures</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
